MacFormat 1997 January/macformat-046.iso/Shareware Plus/Developers/EnterAct/EnterAct Stuff/Documentation/EnterAct in brief

Text File | 1996-09-09 | 21.8 KB | 554 lines | [TEXT/KEEN]

*********EnterAct in brief (this is not the manual) *************
____
Last revised: Sept 1996
____
-----------
Introduction
-----------

EnterAct is a full C/C++/Java project-oriented editor, with
additional code definition display capabilities. And then some.

Most of EnterAct's best features work with first-draft,
uncompilabe code. As long as the delimiters balance and
the key words are not too badly misspelled, EnterAct will
provide instant definition and prototype display, a class
browser, jumping to definitions, cross-referencing etc.

EnterAct typically needs 4-8 Meg for medium to large projects.
(The default 7 Meg partition is recommended for routine work.)
Sorry, that's the price of power. EnterAct is compatible with
Virtual Memory and Ram Doubler™. And more SIMMs/DIMMs.

---------------
Necessary things
---------------

§    Installation
Please see "Installing EnterAct 3/tt". Not much to do, just make
a few aliases and drop them in your EnterAct Stuff folder.

§    Adding Java files
Everything for Java files is the same as for C++ files.
For best results, grab the source for the standard java libraries
somewhere (eg CW9) and add it to your project.

§    Making a new project
Select "New Project" (this same dialog appears when you start up
EnterAct) and cancel the "Open Project"dialog. Give your project a
name, and save it.

In the subsequent "Select <system> Folder..." dialog that appears,
select the folder that holds your system <header> files. If you
have placed EnterAct within a folder that also holds these files,
you can just Cancel. If are leaving EnterAct in its own folder
(the simplest approach) then select your main IDE folder as your
<system> folder. You can drop an alias of your main IDE folder
(eg "Metrowerks CodeWarrior alias") into your EnterAct folder,
and then select the alias as your <system> folder. Please see
"Installing EnterAct 3/tt" for details.

The easiest way to add files to your project is to drag files or
folders or aliases onto your project window. When you do this,
all files in subfolders will also be added.

Or add files with the "Add Files..." or "Add All in Folder..." commands:
hold down the <Shift> key and the latter becomes "Add All in
Subfolders...". With the "Add All" commands, use the button at the
bottom of the dialog to add whole folders at once (including all
files in subfolders if the <Shift> key was down).

Adding all toolbox headers is simplest if you make an alias for
your favorite "Universal Headers" folder, and drag the alias onto
your project window.

You can also add toolbox headers with the "Add Mac Headers"
command. Note this adds the right headers only if your <system>
folder contains exactly one copy of the toolbox headers. If you see
a complaint about multiple versions of the toolbox headers, you
can add the toolbox headers by dragging the actual header folder
(or preferably an alias to it) onto your project window.

Add as many or as few files as you want, regardless of whether
they make up a complete project. Neglect not non-source files
(spec, design etc) which end up in the rightmost project window
pane. Source files are in the left pane, headers in the middle. To
force files with nonstandard extensions into particular panes, use
"File Extensions...." to enter the selection and pick the pane.

Things work best if you include definitions for all the names in
your source code, especially toolbox terms but also PowerPlant or
TCL, ANSI headers, java library source etc. If you make aliases for
these folders and place them in your EnterAct folder, you'll be able
to make new projects easily.

NOTE if a folder's name is in parentheses, the files in it will not
be added to your project. To exclude a folder such as "Old Source",
change its name to "(Old Source)".

If you add more than one file with the same name, truncated full
path names will appear to the right of the file name, to help you
tell which file is which. (See "Building a project dictionary" just
below to exclude files from being built into your dictionary).

The project window responds to many keys in standard ways.
Go left and right across the three panes with the left and right
arrow keys, <Command><down arrow> to go to the bottom of a
pane etc. To type your way to a particular file, you can type
the first part of the name or any distinctive part of the name
(useful if you have a lot of files whose names all begin with the
same prefix, eg to advance to "PROJECT7_Mouse.c" you could
probably type just "mou").

You can open a file from your project window by double-clicking
on it, or hitting <Return>, or use "Go to..." with the name selected.
In all cases, the project window itself will go all the way to the back.

Please add this file to your project for handy reference (use "Add
Front File"), and add the "EnterAct 3 Manual" as well - eventually,
you'll want to browse through it.

§    Building a project dictionary
To exclude a file from being built into your dictionary, hold down
the <Command> key and click on its name in the project window.
A dash '-' will appear to the left of its name, meaning your
dictionary will be "minus" that file.

Select "Update Dictionary". If you run into a problem, see
«EnterAct 3 Manual» 132.
(click in the line above and select "Go to..." from the Search menu -
if you've added the manual to your project, this will open the
manual and take you to the line.)

Now and then (typically when lookup doesn't give expected
results) issue an "Update Dictionary" to keep your
dictionary current. Your dictionary tracks everything defined
outside of function bodies, so if you add a member to a class
or define a new method, your dictionary will be "out of date".
On a 68040 machine running at 25 Mhz an incremental update
takes about 6 secs, a nice little "mini-break".


§    Looking up definitions
The AutoLook window is EnterAct's reason for being, so please
try it out!

Here are a couple of examples, from PowerPlant code.

Double-clicking on "SetPreRecordSelection" (or just clicking after the
name) instantly produces the display shown in the AutoLook window:


























Below, a double-click or click after the name "mTextEngine" shows in the
AutoLook window that it's an "LTextEngine", and the complete definition
of LTextEngine is also shown, for those occasions when you actually
want to do something with one:


























For any sort of lookup to work, you must have a project with
built dictionary open.

Select "AutoLook": when you type or click after or double-click
on a C/C++ or Java name in any window, the AutoLook window
will display its definition. This includes all names for structs,
unions, enums, enum constants, functions, methods, classes, file
or global scope variables, defines, and data members, basically
everything that is defined outside of a function body.

The AutoLook window can also display definitions of local
variables. For this to work, the file in question must be a
source file (ie its name must end in .c or cp etc) and if
you've just created a function you should save the file.
Clicking after a local variable name will then produce a
definition in the AutoLook window.

AutoLook is less accurate in non-source windows, but it still
works.

As of v3.5, AutoLook provides fast extremely accurate lookup for
data member and method names, even in complicated "reference
chains" such as "mObject->SomeMethod().aMember[i].whatsIt"
--just click after any name and the AutoLook window will show
you what it is, or make very good guesses in the rare cases when
the method's context doesn't provide enough scope resolution,
or your spelling is wrong.

For a more permanent separate display of the definition, press the
<Enter> key. A separate lookup window will appear. Hold down the
<Option> key and drag in the lookup window's title bar to select the
exact definition you want from a popup menu. Note that local
variables are at present excluded, you'll have to Copy and Paste
from the AutoLook window if you want a separate view of them.
(Tip: for local variables, click after the type name for the variable
in the AutoLook window, and press <Enter> to create a more
permanent display of the definition in a separate lookup window.)

To look up the struct or class containing a particular member,
again double-click on or click to the right of the name, and press
<Shift><Enter>. A lookup window will appear, holding struct or
class definitions that contain the member. There will often be
several, so use the lookup window's popup menu as described just
above to pick the one you want. The AutoLook window
will usually display the definition you want as soon as you click
to the right of the name, so this isn't much needed unless you
want a separate display of the definition.

To use EnterAct as a lookup aid while working mainly with
some other editor: have a relevant EnterAct project open,
dictionary built, AutoLook open and frontmost; in the other
editor, Copy the term you want looked up, and switch to
EnterAct. If the definition does not immediately appear in
the AutoLook window, press <Commmand><Enter>. If it was
a member name and you want the full definitions of the containing
structs or classes, press <Shift><Command><Enter>.

All lookup windows including AutoLook are fully editable but
cannot be saved.

§    Browsing
Select "Browse" from the EnterAct menu. Browse as in THINK C.
Click and <Shift>click on and off of class names to show/hide
multiple inheritance lines. (As mentioned, class browsing works
with first-draft code.)

To view a particular class, type the first part or some distinctive
part of its name.

You can also use the Find dialog and the Find Again command to
find classes in the browser window (eg if you're looking at the
source for a class and want to see where the class is in the
browser, use Enter Selection to enter the class name in the Find
dialog, then bring the browser to the front and do a Find Again).

"User" class names are underlined, <system> class names are not.

If a class "uses" or "has" member classes, these will be listed
below the main class name, separated from it by a white line.
You can also double-click on these names to jump to their
definitions, or click-and-hold to select one of their method
names from a popup.

The multiple inheritance lines often aren't enough, so if you
<Option> click on a class name you'll see a popup
listing all of the classes from which it is derived. If you let
go the mouse while over one of these base class names you'll
jump to its definition.

If you <Command> click on a class name the resulting popup
will show not only all methods in the class but all methods it
inherits. Note if it's an ENORMOUS list of methods, it make take
5 seconds for the popup to show-please be patient the first
few times you try this.

In all method popups, virtual methods are marked with a "v" so
you can tell at a glance if a method wants or needs or has an
override.

Summary of class popups:
    • click on a class name: all methods defined by the class
    • <Command> click: all inherited methods too
    • <Option> click: the immediate parents of a class.

    Finding Definitions
Single words: <Option>double-click.

Full method names (eg "TCircle::Draw") : select the full name
and use "Find Definition". Or, <Option>double-click on one word,
drag to the other, and release.

Just the method name (eg "Draw") :  normally the AutoLook
window will show just the one you want, but even if it
show several you can jump to it by <Option>double-clicking
on the full method name in the AutoLook window.

If the AutoLook window doesn't show the one you want,
press <Enter>; a lookup window appears holding full
prototypes for all methods with that name; use the lookup
window's popup menu to pick the one you want; then jump
to it as described above for full method names.

More than one definition for a term:
press <Enter> to look the name up; use the popup menu in the
lookup window to pick the definition you want (<Option> click
in the window's title bar); and then use <Option>double-click on
the name, or "Find Definition" without changing the default
selection. The popup menu includes truncated full path names
for the defining files, so you can tell which definition is which.

Static functions and variables: if you're in the file where it is
defined, just <Option>double-click on the name. If you have
several definitions of such a name and you aren't in the file where
it is defined, use the approach for more than one definition described
just above.

§    Multi-file search
The Find dialog contains buttons to select all files of a particular
type in the project window. Files selected for multi-file
operations (including searching) have bullets (•) to their left in
the project window. To "fine tune" your multi-file selection, hold
down the <Option> key and click or drag right in the project
window.

The "Batch" check box allows you to generate a list of all lines
where the search string can be found in your multi-file selection
(the "Find In Next File" button in the Find dialog changes to read
"Batch Find"). To jump to the file and line indicated for one of the
finds that's shown in the result window, click on the line and
use "Go to...".

Multi-file selections have other uses, such as "Remove •'d files",
input for several "Index" commands, and input for hAWK programs
(see the «hAWK User’s Manual»).

Placing a dash '-' beside a project file name indicates that it
should be excluded when building your dictionary, but it's often
the case that you don't want to search those files either.
In the Find dialog, the "Skip '-'" checkbox allows you to exclude
files marked with a dash '-' in the project window when doing
a multi-file operation such as searching.  Please note this
checkbox affects all other buttons in the Find dialog, and all
operations done with the file list. Specifically, the All and
None buttons don't touch files marked with a dash '-' if the
"Skip '-'" checkbox is checked, and such files aren't passed to
a hAWK program, or looked at when you click "Find In Next File".

The "Dual Batch Find" button in the Find dialog calls up a separate
(modal alas) dialog that lets you search for two search strings
that occur within a certain number of lines or characters of each
other. Clicking OK fires off a search of your bulleted files, with
results of the search presented in a text window. "Zero" lines
means on the same line, and a separation of zero characters means
the two strings must occur together with no characters between
(as in "Cmd" and "Handle" matching "CmdHandle" or "HandleCmd").
Dual Batch Find obeys your "Match Words" and "Ignore Case"
settings in the main Find dialog.

§    Accessing THINK Reference
Beside EnterAct at the same level, have a folder entitled "Tools"
or "(Tools)"; drop an alias of THINK Reference in this folder.

To look up THINK Ref's thoughts on a term, select it or click
to the right of it and issue "Find in THINK Reference" (<cmd><->).

§    Accessing Toolbox Assistant
As for THINK Ref, but drop an alias of "QuickView" in your
Tools folder. The "Find in Toolbox Assistant" command is
at the bottom of the Search menu (<cmd><4>).

§    Editing and Undo
All basic editing commands are undoable, with a single level
of undo. This includes Replace All.

You can drag and drop text in the usual way. You can also paste
and delete PICTs to illustrate your documents -- search for
"Illustrating your text" in the «EnterAct 3 Manual».

As you work, EnterAct logs all of your activities (including
contents of edits) to the "EnterAct Recent Activities" file. In a
pinch, you can recover the contents of a delete or remind yourself
of what you just did by selecting "Show Activities..." from
the Edit menu.

Well, not all of your activities, only the last ten thousand.

See «EnterAct 3 Manual» 4600 for a new and nicer way to cut
and paste blocks of code. (To go there: add this file and the
EnterAct 3 Manual to an EnterAct project, then click anywhere
in the first line of this paragraph and use the "Go to" command,
uner the Search menu).

§    Working with Code Warrior
By default, when you open a document and Code Warrior also has
the document open, EnterAct will force Code Warrior to close and
save the file before opening it, asking you first of course before
doing so. To turn this off, deselect the "Safe switching under
MultiFinder" option in the Options... dialog (under the Edit menu).
Having this option on also means that EnterAct will save all your
documents when you switch out, and refresh them from disk
when you switch back if they have been changed by some other
application.

§    The Locations Menu
Select "Add Current Location" to add a sort of "global marker" to
the Locations menu for your current location. This is project
independent, though note the position will not be maintained
if you edit the corresponding source file with another editor.
The text you have selected when you use the Add Current Locations
command will be entered as the default name of the position in
the dialog that subsequently appears: you can edit this name, or
use no name at all and EnterAct will make up a name for you.

To remove a location from this menu:
    • go to the location (typically by picking it from the Locations menu)
    • select Delete Current Location from the Locations menu.

If the location does not exist any more, when you pick it from
the Locations menu you will be told it can't be found, and asked if
you want to delete it from the menu.

You can have up to 10 different locations under this menu.

§    Code Templates
Great fun. All templates are stored in the text file "EnterAct
Code Templates", which is very easy to modify (please take a look
at it). Add this file to the folder where you keep EnterAct, at the
same level.

To use a template, you type its name and press <command><return>.
And <command><return> will also advance you to the next logical
insertion point in your template (or in any code for that matter). If
you save changes to your "EnterAct Code Templates" file using
EnterAct, your new templates are instantly available (no need to
quit and restart). Templates don't have to contain code, and
template names can contain any non-blank characters, not just
letters and numbers.

Each entry has the form
____
ENTRY
entry_name
arbitrary text
    making up the definition
of the entry
END
____

For the complete details on code templates, see the top of
the "EnterAct Code Templates" file. If you'd like to try one
now and you're using EnterAct, open a new window and type
____
html<command><return>
____

Keep all your entries flush-left, and EnterAct will adjust your
indentation when pasting your template in. Just open up a new line
and tab in to the right position before typing the entry name and
pressing <command><return>.

Tip: add "EnterAct Code Templates" to your "Locations" menu so you
can change your templates on the fly.

-----------------
Other useful things
-----------------
You can Balance a delimiter by double-clicking on it.

EnterAct comes equipped with hAWK, a version of AWK. It really
is "three clicks and Run", with many supplied programs. See the
«hAWK User’s Manual» for details. You can also fire off a hAWK
program by using a command line, and you can save the command
line as a "code template" in the "EnterAct Code Templates" file.
If you'd like to try one now and have fully installed EnterAct,
open up a new window and type the word "time", then hit
<command><return> twice. The first <command><return> expands
"time" into a hAWK command line, and the second <command><return>
runs the corresponding hAWK program. Neat, eh?

EnterAct's <Enter>-driven lookup tolerates many kinds of spelling
and (more importantly) memory errors. When in doubt, give it your
best guess and press <Enter>. For extreme cases, use the "Options"
dialog to increase the "Number of entries per lookup window" to 20.
For emergency use only, use <Option><Enter> instead of plain <Enter>
to fire up EnterAct's most error tolerant definition retriever - be
prepared for some wild guesses mixed in there with the good ones!

To look up the last word on the clipboard, typically copied while in
another application, press <Command><Enter>. Note if you have
the AutoLook window open it will automatically show a definition
for a word on the clipboard as you switch back to EnterAct.

"Go to..." is very general. It accepts line numbers, file names, marker
names, and combinations such as file name/marker name, file
name/line number. Handy for placing references in code files to
supporting documentation. Moderately error tolerant, full correct
spelling not required. To see it work, add the "EnterAct 3 Manual" to
your project if you haven't done so, then click anywhere on the
following line and "Go to":
«EnterAct 3 Man» «17   “Go” cmds»

The European-style quotes «» are helpful in most "Go to" link names;
to generate these painlessly, see
«EnterAct 3 Man»  6438 (any individual mark)
and
«EnterAct 3 Man» 8151 (marks in documentation files especially)

To open an included file, click on the line in your source where it's
included and use "Go to".

EnterAct projects accept PICT files.

Printing doesn't clip off long lines, it wraps them around.

EnterAct can be used as the THINK Project Managers's editor,
as explained in either the THINK or EnterAct manuals.

When EnterAct can't locate a project file, and you have enabled
the "Relocate files automatically" option,  it starts searching
at the top of the disk where the file was last seen and
searches down until it finds it (or not). Renaming or moving
a folder does not affect EnterAct's memory of where a file is.
Activating the "Relocate files automatically" option is NOT
recommended, unless you're absolutely sure all your files
have unique names.

If you have favorite AppleScripts to compile projects etc, drop
them in the (EnterAct Scripts) folder for easy access.
The scripts must be compiled scripts, not just text-only.
They should do something simple and straightforward, and then
quit, since you won't be able to continue working in EnterAct
until the script finishes.

That's more than enough to get going. If you become inordinately
fond of EnterAct's definition lookup capabilities, be sure to read
through the full manual for details on the above features and a
host of others.